home *** CD-ROM | disk | FTP | other *** search
/ DS-CD ROM 2 1993 August / DS CD-ROM 2.Ausgabe (August 1993).iso / programm / ds0257 / doc.exe / MQUEUE.DOC < prev    next >
Text File  |  1992-02-11  |  10KB  |  249 lines
  1.   ─────────────────────────────────────────────────────────────────────────────
  2.   Dokumentation zur Datei: MQUEUE.INC
  3.  
  4.   ─────────────────────────────────────────────────────────────────────────────
  5.    
  6.     MQUEUE.INC   - Routinen zur Verwaltung einer Meldungsorientierten Queue
  7.                    (für den Assembler A86)
  8.    
  9.                    (c) Bernd Schemmer 1992
  10.                    Letzter Update: 02.02.1992
  11.    
  12.    
  13.     ■ Beschreibung:
  14.     ---------------
  15.     MQUEUE.INC stellt Routinen zur Verwaltung einer meldungsorientierten
  16.     Queue zur Verfügung. Eine Queue (oder auf deutsch: Schlange) ist eine
  17.     nach dem FIFO-Prinzip (First in, First out) organisierte Datenstruktur
  18.     zur Speicherung von Daten, in diesem Fall von Meldungen, wobei der
  19.     Inhalt der 'Meldungen' für die Routinen völlig unerheblich ist.
  20.    
  21.     Jede Meldung belegt n Byte plus 1 Byte für die Verwaltungsstrukturen,
  22.     wobei n ein Wert im Intervall zwischen 0 und 255 ist.
  23.    
  24.     Die Größe einer Queue, die durch diese Routinen verwaltet werden soll,
  25.     muß zwischen 256 und 65.535 Byte liegen.
  26.    
  27.     Jede Queue beginnt immer mit einem 16 Byte großem Header auf einer
  28.     Segment-Grenze.
  29.    
  30.     Die Routinen unterstützen auch die Einteilung von Meldungen in bis
  31.     zu 256 Klassen.
  32.    
  33.     Jede Queue ist durch einen Semaphor vor gleichzeitiger Bearbeitung
  34.     durch mehrere Prozesse geschützt, wodurch die Queue auch durch
  35.     mehrere verschiedene Prozesse gefüllt und geleert werden kann.
  36.    
  37.     Es ist auch möglich, eine Queue in eine Datei zu sichern und später
  38.     wieder zu laden, da die Routinen nur mit relativen Offsets arbeiten.
  39.     Es muß aber immer die gesamte Queue gesichert und geladen werden.
  40.    
  41.    
  42.     ■ Variablen:
  43.     ------------
  44.     MQueueSeg             - Word, Segment der aktuellen Queue
  45.    
  46.          Alle Routinen (außer InitMQueue) definieren einen zusätzlichen
  47.          Einsprungpunkt 'name_A'. (z.B. für 'LockMQueue' ist dies
  48.          'LockMQueue_A'). Falls die Routinen über diesen Einsprungpunkt
  49.          aufgerufen werden, arbeiten sie mit der Queue, deren Segment
  50.          in dieser Variable gespeichert ist. (Der Wert des Registers ES
  51.          beim Aufruf ist in diesen Fall ohne Bedeutung, das Register ES
  52.          wird aber NICHT gesichert.) Die Variable muß in diesem Fall
  53.          vorher auf einen korrekten Wert gesetzt worden sein! (z.B. durch
  54.          den Aufruf von 'InitMQueue' oder durch direktes Setzen)
  55.          Falls die Routinen über den normalen Einsprungpunkt aufgerufen
  56.          werden, wird diese Variable weder genutzt noch verändert.
  57.    
  58.     MQueueSeg:[MQueueUserData1] - Word, für Benutzerzwecke reserviert
  59.     MQueueSeg:[MQueueUserData2] - Word, für Benutzerzwecke reserviert
  60.    
  61.          An den Offsets MQueueUserData1 und MQueueUserData2 im Header
  62.          der Queue sind jeweils 2 Byte (= 1 Wort) für Daten des Programms
  63.          reserviert. Diese beiden Wörter werden von den Routinen zur
  64.          Verwaltung der Queue weder gelesen noch verändert (also auch
  65.          nicht mit einem bestimmten Wert initialisiert!).
  66.          (MQueueUserData1 und MQueueUserData2 sind über 'dw' definiert)
  67.    
  68.    
  69.     Alle anderen Variablen zur Verwaltung der Queue werden im Speicher-
  70.     bereich für die Queue angelegt und sollten von anderen Routinen
  71.     weder gelesen noch verändert werden.
  72.    
  73.    
  74.     ■ Routinen:
  75.     -----------
  76.     InitMQueue             - Initialisert (d.h. löscht) die Queue
  77.     LockMQueue             - Sperrt eine Queue
  78.     UnLockMQueue           - Gibt eine Queue wieder frei
  79.     DeleteMQueue           - Löscht die gesamte Queue
  80.     WriteMQueue            - Schreibt eine neue Meldung in die Queue
  81.     LookMQueue             - Ermittelt die Länge und die Klasse der nächsten
  82.                              Meldung aus der Queue
  83.     ReadMQueue             - Liest die nächste Meldung aus der Queue
  84.     GetMQueueStatistik     - Ermittelt die Daten der Queue
  85.    
  86.     Da alle Variablen zur Verwaltung der Queue im Segment der Queue
  87.     angelegt werden, können die Routinen auch mit mehreren Queuen
  88.     gleichzeitig arbeiten.
  89.    
  90.     Hinweis: Da nicht alle verwendeten Namen und Bezeichner dieser Datei
  91.              dokumentiert sind, sollten bei Nutzung dieser Routinen in
  92.              den anderen Quelltexten keine Namen oder Bezeichner, die
  93.              die Zeichenkette 'MQueue' enthalten, verwendet werden.
  94.    
  95.    
  96.     ■ Fehlernummern der Routinen
  97.     ----------------------------
  98.    
  99.     Alle Fehlernummern der Routinen haben das Format 82xx, wobei xx die
  100.     Nummer des eigentlichen Fehlers ist.
  101.    
  102.     Name                   Nummer   Bedeutung
  103.     ----------------------------------------------------------------------
  104.     MQueueIsEmpty      EQU 08201h ; Es ist keine Meldung in der Queue
  105.    
  106.     MQueueIsFull       EQU 08202h ; Es ist nicht mehr genügend freier
  107.                                   ; Speicher zur Aufnahme der neuen Meldung
  108.                                   ; in der Queue frei
  109.    
  110.     MQueueLengthError  EQU 08203h ; falsche Größe für die Queue angegeben
  111.    
  112.     MQueueBufferError  EQU 08204h ; Puffer ist für die nächste Meldung zu
  113.                                   ; klein
  114.    
  115.     MQueueMessageError EQU 08205h ; Die Meldung ist zu lang
  116.    
  117.     MQueueAktivError   EQU 082FFh ; gleichzeigtiger Zugriff von mehreren
  118.                                   ; Prozessen auf eine Queue nicht möglich
  119.    
  120.    
  121.     ----------------------------
  122.     InitMQueue
  123.    
  124.     Funktion: Initialisiert die Queue
  125.    
  126.     Eingabe:  ES = Segment für die Queue
  127.                    Die Queue beginnt immer am Offset 0
  128.               CX = Größe des Speicherbereichs in Byte für die Queue
  129.                    Es muß gelten: 256 < CX < 65.535
  130.    
  131.     Ausgabe:  CF = 0 ->> okay
  132.                          CX = freier Speicher in der Queue
  133.               CF = 1 ->> Fehler
  134.                          AX = Fehlernummer
  135.                          Die Queue wurde NICHT eingerichtet.
  136.    
  137.     Bes.:     Das Segment der Queue wird, falls kein Fehler auftritt, in
  138.               der Variablen MQueueSeg gespeichert.
  139.               Der Wert des Semaphors der Queue wird NICHT berücksichtigt!
  140.    
  141.     ----------------------------
  142.     DeleteMQueue
  143.    
  144.     Funktion: Löscht die gesamte Queue
  145.    
  146.     Eingabe:  ES = Segment der Queue
  147.    
  148.     Ausgabe:  CF = 0 ->> okay
  149.                          CX = freier Speicher in der Queue
  150.               CF = 1 ->> Fehler
  151.                          AX = Fehlernummer
  152.    
  153.     ----------------------------
  154.     LockMQueue
  155.    
  156.     Funktion: Sperrt eine Queue
  157.    
  158.     Eingabe:  ES = Segment der Queue
  159.    
  160.     Ausgabe:  CF = 0 ->> okay
  161.               CF = 1 ->> Fehler
  162.                          AX = Fehlernummer
  163.    
  164.     ----------------------------
  165.     UnLockMQueue
  166.    
  167.     Funktion: Gibt eine Queue wieder frei
  168.    
  169.     Eingabe:  ES = Segment der Queue
  170.    
  171.     Ausgabe:  CF = 0 ->> okay
  172.               CF = 1 ->> Fehler
  173.                          AX = Fehlernummer
  174.    
  175.     Bes.:     Der Wert des Semaphors der Queue wird NICHT berücksichtigt!
  176.    
  177.     ----------------------------
  178.     GetMQueueStatistik
  179.    
  180.     Funktion: Ermittelt die statistischen Daten der Queue
  181.    
  182.     Eingabe:  ES = Segment der Queue
  183.    
  184.     Ausgabe:  CF = 0 ->> okay
  185.                          CX = freier Speicher in der Queue
  186.                          DX = Größe der Queue
  187.                          AX = Anzahl der Meldungen in der Queue
  188.               CF = 1 ->> Fehler
  189.                          AX = Fehlernummer
  190.    
  191.     ----------------------------
  192.     WriteMQueue
  193.    
  194.     Funktion: Schreibt eine Meldung in die Queue
  195.    
  196.     Eingabe:  ES = Segment der Queue
  197.               CX = Länge der Meldung
  198.               DS:SI -> Meldung
  199.    
  200.     Ausgabe:  CF = 0 ->> okay
  201.               CF = 1 ->> Fehler
  202.                          AX = Fehlernummer
  203.                          und falls AX = MQueueIsFull ist:
  204.                          CX = max. Länge einer weiteren Meldung für die Queue
  205.                               falls CX = -1 ->> keine weitere Meldung möglich
  206.    
  207.     Bes.:     Das Directionflag wird gelöscht.
  208.    
  209.     ----------------------------
  210.     LookMQueue
  211.    
  212.     Funktion: Ermittelt die Daten der nächsten Meldung aus der Queue
  213.    
  214.     Eingabe:  ES = Segment der Queue
  215.    
  216.     Ausgabe:  CF = 0 ->> okay
  217.                          CX = Länge der nächsten Meldung
  218.                          und falls CX <> 0:
  219.                          AL = 1. Byte der Meldung
  220.               CF = 1 ->> Fehler
  221.                          AX = Fehlernummer
  222.    
  223.     Bes.:     Die Klasse von Meldungen kann im 1. Byte einer Meldung
  224.               gesichert werden, da dieses Byte auch durch den Look-
  225.               Ahead-Aufruf zurückgeliefert wird.
  226.               Das Directionflag wird gelöscht.
  227.    
  228.     ----------------------------
  229.     ReadMQueue
  230.    
  231.     Funktion: Liest die nächste Meldung aus der Queue
  232.    
  233.     Eingabe:  ES = Segment der Queue
  234.               CX = Länge des Puffers für die Meldung
  235.               DS:SI -> Puffer für die Meldung
  236.    
  237.     Ausgabe:  CF = 0 ->> okay
  238.                          Meldung steht im Puffer bei DS:SI
  239.                          CX = Länge der Meldung
  240.               CF = 1 ->> Fehler
  241.                          AX = Fehlernummer
  242.    
  243.     Bes.:     Falls diese Routine mit CX = 0 aufgerufen wird, verhält
  244.               sie sich wie die Routine 'LookMQueue'.
  245.               Falls der Puffer bei DS:SI für die Meldung zu klein ist,
  246.               wird die Meldung NICHT aus der Queue entfernt.
  247.               Das Directionflag wird gelöscht.
  248.    
  249.